The section describes the programming interface of the I2C HAL driver. More...

Data Structures
struct	i2c_config_t
	I2C module configuration. More...

Enumerations
enum	i2c_status_t { kStatus_I2C_Success = 0, kStatus_I2C_OutOfRange, kStatus_I2C_InvalidArgument, kStatus_I2C_Fail, kStatus_I2C_Busy, kStatus_I2C_Timeout, kStatus_I2C_ReceivedNak, kStatus_I2C_SlaveTxUnderrun, kStatus_I2C_SlaveRxOverrun, kStatus_I2C_AribtrationLost }
	I2C status return codes. More...

enum	i2c_transmit_receive_mode_t { kI2CReceive = 0, kI2CTransmit = 1 }
	Direction of master and slave transfers. More...

Module controls
void	i2c_hal_init (uint32_t instance, const i2c_config_t *config, uint32_t sourceClockInHz)
	Initializes and configures the I2C peripheral. More...

void	i2c_hal_reset (uint32_t instance)
	Restores the I2C peripheral to reset state. More...

static void	i2c_hal_enable (uint32_t instance)
	Enables the I2C module operation. More...

static void	i2c_hal_disable (uint32_t instance)
	Disables the I2C module operation. More...

DMA
static void	i2c_hal_set_dma_enable (uint32_t instance, bool enable)
	Enables or disables the DMA support. More...

Pin functions
static void	i2c_hal_set_high_drive (uint32_t instance, bool enable)
	Controls the drive capability of the I2C pads. More...

static void	i2c_hal_set_glitch_filter (uint32_t instance, uint8_t glitchWidth)
	Controls the width of the programmable glitch filter. More...

Low power
static void	i2c_hal_set_wakeup_enable (uint32_t instance, bool enable)
	Controls the I2C wakeup enable. More...

Baud rate
uint32_t	i2c_hal_get_max_baud (uint32_t instance, uint32_t sourceClockInHz)
	brief Returns the maximum supported baud rate in kilohertz. More...

i2c_status_t	i2c_hal_set_baud (uint32_t instance, uint32_t sourceClockInHz, uint32_t kbps, uint32_t *absoluteError_Hz)
	Sets the I2C bus frequency for master transactions. More...

static void	i2c_hal_set_baud_icr (uint32_t instance, uint8_t mult, uint8_t icr)
	Sets the I2C baud rate multiplier and table entry. More...

static void	i2c_hal_set_independent_slave_baud (uint32_t instance, bool enable)
	Slave baud rate control. More...

Bus operations
void	i2c_hal_send_start (uint32_t instance)
	Sends a START or a Repeated START signal on the I2C bus. More...

static void	i2c_hal_send_stop (uint32_t instance)
	Sends a STOP signal on the I2C bus. More...

static void	i2c_hal_set_direction (uint32_t instance, i2c_transmit_receive_mode_t mode)
	Selects either transmit or receive modes. More...

static i2c_transmit_receive_mode_t	i2c_hal_get_direction (uint32_t instance)
	Returns the currently selected transmit or receive mode. More...

static void	i2c_hal_send_ack (uint32_t instance)
	Causes an ACK to be sent on the bus. More...

static void	i2c_hal_send_nak (uint32_t instance)
	Causes a NAK to be sent on the bus. More...

Data transfer
static uint8_t	i2c_hal_read (uint32_t instance)
	Returns the last byte of data read from the bus and initiate another read. More...

static void	i2c_hal_write (uint32_t instance, uint8_t data)
	Writes one byte of data to the I2C bus. More...

Slave address
void	i2c_hal_set_slave_address_7bit (uint32_t instance, uint8_t address)
	Sets the primary 7-bit slave address. More...

void	i2c_hal_set_slave_address_10bit (uint32_t instance, uint16_t address)
	Sets the primary slave address and enables 10-bit address mode. More...

static void	i2c_hal_set_general_call_enable (uint32_t instance, bool enable)
	Controls whether the general call address is recognized. More...

static void	i2c_hal_set_slave_range_address_enable (uint32_t instance, bool enable)
	Enables or disables the slave address range matching. More...

static void	i2c_hal_set_upper_slave_address_7bit (uint32_t instance, uint8_t address)
	Sets the upper slave address. More...

Status
static bool	i2c_hal_is_master (uint32_t instance)
	Returns whether the I2C module is in master mode. More...

static bool	i2c_hal_is_transfer_complete (uint32_t instance)
	Gets the transfer complete flag. More...

static bool	i2c_hal_is_addressed_as_slave (uint32_t instance)
	Returns whether the I2C slave was addressed. More...

static bool	i2c_hal_is_bus_busy (uint32_t instance)
	Determines whether the I2C bus is busy. More...

static bool	i2c_hal_was_arbitration_lost (uint32_t instance)
	Returns whether the arbitration procedure was lost. More...

static void	i2c_hal_clear_arbitration_lost (uint32_t instance)
	Clears the arbitration lost flag. More...

static bool	i2c_hal_is_range_address_match (uint32_t instance)
	Get the range address match flag. More...

static i2c_transmit_receive_mode_t	i2c_hal_get_slave_direction (uint32_t instance)
	Returns whether the I2C slave was addressed in read or write mode. More...

static bool	i2c_hal_get_receive_ack (uint32_t instance)
	Returns whether an ACK was received after the last byte was transmitted. More...

Interrupt
static void	i2c_hal_enable_interrupt (uint32_t instance)
	Enables the I2C interrupt requests. More...

static void	i2c_hal_disable_interrupt (uint32_t instance)
	Disables the I2C interrupt requests. More...

static bool	i2c_hal_is_interrupt_enabled (uint32_t instance)
	Returns whether the I2C interrupts are enabled. More...

static bool	i2c_hal_get_interrupt_status (uint32_t instance)
	Returns the current I2C interrupt flag. More...

static void	i2c_hal_clear_interrupt (uint32_t instance)
	Clears the I2C interrupt if set. More...

I2C HAL Driver

ICR Table

ICR (hex)	SCL divider	SDA hold value	SCL start hold value	SCL stop hold value
00	20	7	6	11
01	22	7	7	12
02	24	8	8	13
03	26	8	9	14
04	28	9	10	15
05	30	9	11	16
06	34	10	13	18
07	40	10	16	21

Clock rate formulas

I2C baud rate = bus_clock_Hz / (mult * SCL_divider)SDA hold time = bus_clock_period_s * mult * SDA_hold_valueSCL start hold time = bus_clock_period_s * mult * SCL_start_hold_valueSCL stop hold time = bus_clock_period_s * mult * SCL_stop_hold_value

Data Structure Documentation

struct i2c_config_t

Pass an instance of this structure to the i2c_hal_init() to configure the entire I2C peripheral in a single function call.

Data Fields
bool	enableModule
	Whether the I2C peripheral operation is enabled. More...

uint32_t	baudRate_kbps
	Requested baud rate in kilobits per second, for example, 100 or 400. More...

bool	useIndependentSlaveBaud
	Enables independent slave mode baud rate at maximum frequency. More...

bool	enableInterrupt
	Enable for the I2C interrupt. More...

bool	enableDma
	Enable DMA transfer signalling. More...

bool	enableHighDrive
	Enable high drive pin mode. More...

bool	enableWakeup
	Enable low power wakeup. More...

uint8_t	glitchFilterWidth
	Specify the glitch filter width in terms of bus clock cycles. More...

uint16_t	slaveAddress
	7-bit or 10-bit slave address. More...

uint8_t	upperSlaveAddress
	7-bit upper slave address, or zero to disable. More...

bool	use10bitSlaveAddress
	Controls whether 10-bit slave addresses are enabled. More...

bool	enableGeneralCallAddress
	Enable general call address matching. More...

bool	enableRangeAddressMatch
	Determines if addresses between slaveAddress and upperSlaveAddress are matched. More...

Field Documentation

bool i2c_config_t::enableModule

uint32_t i2c_config_t::baudRate_kbps

Pass zero to not set the baud rate.

bool i2c_config_t::useIndependentSlaveBaud

bool i2c_config_t::enableInterrupt

bool i2c_config_t::enableDma

bool i2c_config_t::enableHighDrive

bool i2c_config_t::enableWakeup

uint8_t i2c_config_t::glitchFilterWidth

Set this value to zero to disable the glitch filter.

uint16_t i2c_config_t::slaveAddress

uint8_t i2c_config_t::upperSlaveAddress

If 10-bit addresses are enabled, the top 3 bits are provided by the slaveAddress field.

bool i2c_config_t::use10bitSlaveAddress

bool i2c_config_t::enableGeneralCallAddress

bool i2c_config_t::enableRangeAddressMatch

Both of those fields must be non-zero.

Enumeration Type Documentation

enum i2c_status_t

Enumerator
kStatus_I2C_Busy	The master is already performing a transfer.
kStatus_I2C_Timeout	The transfer timed out.
kStatus_I2C_ReceivedNak	The slave device sent a NAK in response to a byte.
kStatus_I2C_SlaveTxUnderrun	I2C Slave TX Underrun error.
kStatus_I2C_SlaveRxOverrun	I2C Slave RX Overrun error.
kStatus_I2C_AribtrationLost	I2C Arbitration Lost error.

enum i2c_transmit_receive_mode_t

Enumerator
kI2CReceive	Master and slave receive.
kI2CTransmit	Master and slave transmit.

Function Documentation

void i2c_hal_init	(	uint32_t	instance,
		const i2c_config_t *	config,
		uint32_t	sourceClockInHz
	)

Parameters

instance	The I2C peripheral instance number
config	Pointer to the configuration settings
sourceClockInHz	I2C source input clock in Hertz.

void i2c_hal_reset ( uint32_t instance )

Parameters

instance The I2C peripheral instance number

static void i2c_hal_enable ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

static void i2c_hal_disable ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

static void i2c_hal_set_dma_enable	(	uint32_t	instance,
		bool	enable
	)

inlinestatic

Parameters

instance	The I2C peripheral instance number
enable	Pass true to enable DMA transfer signalling

static void i2c_hal_set_high_drive	(	uint32_t	instance,
		bool	enable
	)

inlinestatic

Parameters

instance	The I2C peripheral instance number
enable	Passing true will enable high drive mode of the I2C pads. False sets normal drive mode.

static void i2c_hal_set_glitch_filter	(	uint32_t	instance,
		uint8_t	glitchWidth
	)

inlinestatic

Controls the width of the glitch, in terms of bus clock cycles, that the filter must absorb. The filter does not allow any glitch whose size is less than or equal to this width setting, to pass.

Parameters

instance	The I2C peripheral instance number
glitchWidth	Maximum width in bus clock cycles of the glitches that is filtered. Pass zero to disable the glitch filter.

static void i2c_hal_set_wakeup_enable	(	uint32_t	instance,
		bool	enable
	)

inlinestatic

The I2C module can wake the MCU from low power mode with no peripheral bus running when slave address matching occurs.

Parameters

instance	The I2C peripheral instance number.
enable	true - Enables the wakeup function in low power mode. false - Normal operation. No interrupt is generated when address matching in low power mode.

uint32_t i2c_hal_get_max_baud	(	uint32_t	instance,
		uint32_t	sourceClockInHz
	)

Parameters

instance	The I2C peripheral instance number
sourceClockInHz	I2C source input clock in Hertz

Returns: The maximum baud rate in kilohertz

i2c_status_t i2c_hal_set_baud	(	uint32_t	instance,
		uint32_t	sourceClockInHz,
		uint32_t	kbps,
		uint32_t *	absoluteError_Hz
	)

Parameters

instance	The I2C peripheral instance number
sourceClockInHz	I2C source input clock in Hertz
kbps	Requested bus frequency in kilohertz. Common values are either 100 or 400.
absoluteError_Hz	If this parameter is not NULL, it is filled in with the difference in Hertz between the requested bus frequency and the closest frequency possible given available divider values.

Return values

kStatus_Success	The baud rate was changed successfully. However, there is no guarantee on the minimum error. If you want to ensure that the baud was set to within a certain error, then use the absoluteError_Hz parameter.
kStatus_OutOfRange	The requested baud rate was not within the range of rates supported by the peripheral.

static void i2c_hal_set_baud_icr	(	uint32_t	instance,
		uint8_t	mult,
		uint8_t	icr
	)

inlinestatic

Use this function to set the I2C bus frequency register values directly, if they are known in advance.

Parameters

instance	The I2C peripheral instance number
mult	Value of the MULT bitfield, ranging from 0-2.
icr	The ICR bitfield value, which is the index into an internal table in the I2C hardware that selects the baud rate divisor and SCL hold time.

static void i2c_hal_set_independent_slave_baud	(	uint32_t	instance,
		bool	enable
	)

inlinestatic

Enables an independent slave mode baud rate at the maximum frequency. This forces clock stretching on the SCL in very fast I2C modes.

Parameters

instance	The I2C peripheral instance number
enable	true - Slave baud rate is independent of the master baud rate; false - The slave baud rate follows the master baud rate and clock stretching may occur.

void i2c_hal_send_start ( uint32_t instance )

This function is used to initiate a new master mode transfer by sending the START signal. It is also used to send a Repeated START signal when a transfer is already in progress.

Parameters

instance The I2C peripheral instance number

static void i2c_hal_send_stop ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

static void i2c_hal_set_direction	(	uint32_t	instance,
		i2c_transmit_receive_mode_t	mode
	)

inlinestatic

Parameters

instance	The I2C peripheral instance number
mode	Specifies either transmit mode or receive mode. The valid values are: kI2CTransmit kI2CReceive

static i2c_transmit_receive_mode_t i2c_hal_get_direction ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

kI2CTransmit	I2C is configured for master or slave transmit mode.
kI2CReceive	I2C is configured for master or slave receive mode.

static void i2c_hal_send_ack ( uint32_t instance )

inlinestatic

This function specifies that an ACK signal is sent in response to the next received byte.

Note that the behavior of this function is changed when the I2C peripheral is placed in Fast ACK mode. In this case, this function causes an ACK signal to be sent in response to the current byte, rather than the next received byte.

Parameters

instance The I2C peripheral instance number

static void i2c_hal_send_nak ( uint32_t instance )

inlinestatic

This function specifies that a NAK signal is sent in response to the next received byte.

Note that the behavior of this function is changed when the I2C peripheral is placed in the Fast ACK mode. In this case, this function causes an NAK signal to be sent in response to the current byte, rather than the next received byte.

Parameters

instance The I2C peripheral instance number

static uint8_t i2c_hal_read ( uint32_t instance )

inlinestatic

In a master receive mode, calling this function initiates receiving the next byte of data.

Parameters

instance The I2C peripheral instance number

Returns: This function returns the last byte received while the I2C module is configured in master receive or slave receive mode.

static void i2c_hal_write	(	uint32_t	instance,
		uint8_t	data
	)

inlinestatic

When this function is called in the master transmit mode, a data transfer is initiated. In slave mode, the same function is available after an address match occurs.

In a master transmit mode, the first byte of data written following the start bit or repeated start bit is used for the address transfer and must consist of the slave address (in bits 7-1) concatenated with the required R/#W bit (in position bit 0).

Parameters

instance	The I2C peripheral instance number
data	The byte of data to transmit

void i2c_hal_set_slave_address_7bit	(	uint32_t	instance,
		uint8_t	address
	)

Parameters

instance	The I2C peripheral instance number
address	The slave address in the upper 7 bits. Bit 0 of this value must be 0.

void i2c_hal_set_slave_address_10bit	(	uint32_t	instance,
		uint16_t	address
	)

Parameters

instance	The I2C peripheral instance number
address	The 10-bit slave address, in bits [10:1] of the value. Bit 0 must be 0.

static void i2c_hal_set_general_call_enable	(	uint32_t	instance,
		bool	enable
	)

inlinestatic

Parameters

instance	The I2C peripheral instance number
enable	Whether to enable the general call address.

static void i2c_hal_set_slave_range_address_enable	(	uint32_t	instance,
		bool	enable
	)

inlinestatic

Parameters

instance	The I2C peripheral instance number
enable	Pass true to enable the range address matching. You must also call the i2c_hal_set_upper_slave_address_7bit() to set the upper address.

static void i2c_hal_set_upper_slave_address_7bit	(	uint32_t	instance,
		uint8_t	address
	)

inlinestatic

This slave address is used as a secondary slave address. If range address matching is enabled, this slave address acts as the upper bound on the slave address range.

This function sets only a 7-bit slave address. If 10-bit addressing was enabled by calling the i2c_hal_set_slave_address_10bit(), then the top 3 bits set with that function are also used with the address set with this function to form a 10-bit address.

Passing 0 for the address parameter disables matching the upper slave address.

Parameters

instance	The I2C peripheral instance number
address	The upper slave address in the upper 7 bits. Bit 0 of this value must be 0. This address must be greater than the primary slave address that is set by calling the i2c_hal_set_slave_address_7bit().

static bool i2c_hal_is_master ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	The module is in master mode, which implies it is also performing a transfer.
false	The module is in slave mode.

static bool i2c_hal_is_transfer_complete ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	Transfer is complete.
false	Transfer is in progress.

static bool i2c_hal_is_addressed_as_slave ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	Addressed as slave.
false	Not addressed.

static bool i2c_hal_is_bus_busy ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	Bus is busy.
false	Bus is idle.

static bool i2c_hal_was_arbitration_lost ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	Loss of arbitration
false	Standard bus operation

static void i2c_hal_clear_arbitration_lost ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

static bool i2c_hal_is_range_address_match ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	Addressed as slave.
false	Not addressed.

static i2c_transmit_receive_mode_t i2c_hal_get_slave_direction ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

kI2CReceive	Slave receive, master writing to slave
kI2CTransmit	Slave transmit, master reading from slave

static bool i2c_hal_get_receive_ack ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	Acknowledges that the signal was received after the completion of one byte of data transmission on the bus.
false	No acknowledgement of the signal is detected.

static void i2c_hal_enable_interrupt ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

static void i2c_hal_disable_interrupt ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

static bool i2c_hal_is_interrupt_enabled ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	I2C interrupts are enabled.
false	I2C interrupts are disabled.

static bool i2c_hal_get_interrupt_status ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

Return values

true	An interrupt is pending.
false	No interrupt is pending.

static void i2c_hal_clear_interrupt ( uint32_t instance )

inlinestatic

Parameters

instance The I2C peripheral instance number

ICR (hex)	SCL divider	SDA hold value	SCL start hold value	SCL stop hold value
00	20	7	6	11
01	22	7	7	12
02	24	8	8	13
03	26	8	9	14
04	28	9	10	15
05	30	9	11	16
06	34	10	13	18
07	40	10	16	21

ICR (hex)	SCL divider	SDA hold value	SCL start hold value	SCL stop hold value
00	20	7	6	11
01	22	7	7	12
02	24	8	8	13
03	26	8	9	14
04	28	9	10	15
05	30	9	11	16
06	34	10	13	18
07	40	10	16	21

Data Structures

Enumerations

Module controls

DMA

Pin functions

Low power

Baud rate

Bus operations

Data transfer

Slave address

Status

Interrupt

I2C HAL Driver

ICR Table

Clock rate formulas

Data Structure Documentation

Data Fields

Field Documentation

Enumeration Type Documentation

Function Documentation

ICR (hex)	SCL divider	SDA hold value	SCL start hold value	SCL stop hold value
00	20	7	6	11
01	22	7	7	12
02	24	8	8	13
03	26	8	9	14
04	28	9	10	15
05	30	9	11	16
06	34	10	13	18
07	40	10	16	21